\documentclass{book}
\usepackage{todonotes}
\usepackage{fullpage}
\usepackage{xspace}
\usepackage{ulem} % Decent underlining
\usepackage{tikz}
\usetikzlibrary{shadows}
\usepackage{color}
\usepackage{makeidx}
\usepackage{ifxetex}
\ifxetex
\usepackage[xetex,final,linktocpage]{hyperref}
\usepackage{fontspec}
\usepackage{xltxtra}
\defaultfontfeatures{Mapping=tex-text,SmallCapsFeatures={Letters=SmallCaps}}

% Obtain the CMU fonts from http://sf.net/projects/cm-unicode/ if you don't 
% have them
\setromanfont[Ligatures={Common}]{CMU Serif}

\else
\usepackage[final,linktocpage]{hyperref}
% Now, fix the small-cap (\textsc{}) bug
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\fi
\definecolor{Blue}{rgb}{0.2,0.2,0.8}
\definecolor{Green}{rgb}{0.1,0.5,0.1}
\definecolor{DkBlue}{rgb}{0.1,0.1,0.5}
\definecolor{darkbrown}{rgb}{0.30, 0.30, 0.00}
\definecolor{postit}{rgb}{0.97,1.0,0.54}
\title{The Open Community Runtime API\\{\large \textsc{Version 0.1}}}
\author{~}
\newcommand{\tbh}[1]{\textsc{#1}}

\newcommand{\barefunc}[1]{\textsf{\textbf{#1}}}
\newcommand{\hfunc}[1]{\barefunc{#1}}
\newcommand{\func}[1]{\barefunc{\color{DkBlue}{#1}}}
\newcommand{\funcIdx}[1]{\func{#1}%
\index{functions!\barefunc{#1}}%
\index{#1@\barefunc{#1} (function)}}
\newcommand{\SavedFuncDesc}{}
\newenvironment{FuncDesc}[1]
    {\subsection{\hfunc{#1()}}\renewcommand{\SavedFuncDesc}{#1}\index{functions!\barefunc{#1}|textbf|(}%
\index{#1@\barefunc{#1} (function)|textbf|(}}
    {\index{functions!\barefunc{\SavedFuncDesc}|textbf|)}%
\index{\SavedFuncDesc @\barefunc{\SavedFuncDesc} (function)|textbf|)}}
\newcommand{\argref}[1]{\textit{#1}}

\newcommand{\dtypeNoIdx}[1]{\texttt{\textbf{\color{Green}{#1}}}}
\newcommand{\dtypeIdx}[1]{\dtypeNoIdx{#1}%
\index{data types!\texttt{#1}}%
\index{#1@\texttt{#1} (data type)}}
\newcommand{\dtype}[1]{\dtypeNoIdx{#1}}

\newcommand{\retcode}[1]{\texttt{\textbf{#1}}}
\newcommand{\retcodeIdx}[1]{\retcode{#1}%
\index{return codes!\retcode{#1}}%
\index{#1@\retcode{#1} (return code)}}

\newcommand{\const}[1]{\texttt{#1}}
\newcommand{\constIdx}[1]{\const{#1}%
\index{constants!\const{#1}}%
\index{#1@\const{#1} (constant)}}

\newcommand{\fname}[1]{\texttt{#1}%
\index{files!\texttt{#1}}%
\index{#1@\texttt{#1} (file)}}
\newcommand{\field}[1]{%
\index{structure fields and argument names!#1}%
\index{#1 (field)}%
\textcolor{darkbrown}{\textit{#1}}\xspace%
}

\newcommand{\ptblshadowbox}[3]{%
  \begin{tikzpicture}
    \node[drop shadow,#2] {\begin{minipage}[t][][t]{#1}%
      #3
    \end{minipage}};
  \end{tikzpicture}}
\newcommand{\ptblbigshadowbox}[3]{%
  \begin{tikzpicture}
    \node[drop shadow={shadow xshift=.4em, shadow yshift=-0.4em},#2] %
      {\begin{minipage}[t][][t]{#1}%
      #3
    \end{minipage}};
  \end{tikzpicture}}

\newcommand{\bareprototype}[3]{\hfill\ptblbigshadowbox{0.85\textwidth}%
{rectangle,inner sep=5pt,thick,draw=black,
top color=white,bottom color=white}{
\begin{tabular}{rcp{10cm}}
\dtypeNoIdx{#1}&\func{#2}&(\parbox[t]{9.5cm}{\raggedright\noindent
#3);}
\end{tabular}
}\hfill}
\newcommand{\prototype}[3]{\subsubsection*{Function Prototype for 
\hfunc{#2}}\bareprototype{#1}{#2}{#3}}
\newcommand{\lastargument}[2]{\dtypeNoIdx{#1} {#2}}
\newcommand{\argument}[2]{\lastargument{#1}{#2},\\}
\newcommand{\voidarg}{\dtypeNoIdx{void}}

\newlength{\rcwidth}
\newlength{\rcdescwidth}
\settowidth{\rcwidth}{\retcodeIdx{OCR\_INVAL}}
\setlength{\rcdescwidth}{\textwidth - \rcwidth - \tabcolsep - 2\parindent}
\newcommand{\rc}[2]{{#1}\vspace{.5em} & 
{\parbox[t]{\rcdescwidth}{\raggedright\noindent 
#2}}\vspace{.5em}\tabularnewline}
\newenvironment{ReturnCodes}[1][Return Codes]
{\subsubsection*{#1}
    \begin{tabular}[c]{p{\rcwidth}p{\rcdescwidth}}
}
{
    \end{tabular}
}

\newlength{\argwidth}
\newlength{\argdescwidth}
\newlength{\opwidth}
\settowidth{\argwidth}{\field{new\_value}}
\settowidth{\opwidth}{\textbf{output}}
\setlength{\argdescwidth}{\textwidth - \argwidth - 2\tabcolsep - 3\parindent - \opwidth}
\newcommand{\argdesc}[3]{{\parbox{\argwidth}{\raggedright 
\textit{#1}}}\vspace{.5em} & {\noindent \textbf{#2}}\vspace{.5em} & 
{\parbox[t]{\argdescwidth}{\raggedright\noindent 
#3}}\vspace{.5em}\tabularnewline}
\newenvironment{ArgDesc}
{\subsubsection*{Arguments}
    \begin{tabular}[c]{p{\argwidth}p{\opwidth}p{\argdescwidth}}
}
{
    \end{tabular}
}

\makeindex

%
% Implementation notes
% \impnote{caption}{text}
%     Puts text into a floating box and lists caption in the table of imp notes
%
\makeatletter
\newcommand{\listofimps}{%
\chapter*{List of Implementation Notes}\@starttoc{imp}%
}
% \newcommand{\l@impnotes}{\@dottedtocline{1}{1.5em}{2.3em}}
\makeatother

\newcounter{impnum}
\newlength{\implwidth}\setlength{\implwidth}{.60\textwidth}
\addtolength{\implwidth}{\widthof{\textbf{\textsc{Implementation}}}}
\addtolength{\implwidth}{\columnsep}
\newenvironment{IMP}[2]{
\refstepcounter{impnum}
    \begin{flushright}
    \ptblshadowbox{\implwidth}{rectangle,inner sep=10pt,
                        fill,thick,draw=black,top color=white,
                        bottom color=white}{
    \addcontentsline{imp}{section}{\protect\numberline{\theimpnum} #1}
    \begin{tabular}{cl}
        \textbf{\textsc{Implementation}} & \\
        \textbf{\textsc{note \theimpnum:}} & \raisebox{1.5ex}[0pt]{\uline{#1}}\\
        & \parbox{.60\textwidth}{\raggedright \textsf{#2}}\\
    \end{tabular}
    }
    \end{flushright}
}{
}

\newcommand{\impnote}[2]{
\begin{IMP}{#1}{#2}
\end{IMP}
}
%\renewcommand{\impnote}[2]{}% To "erase" implementation notes

\begin{document}
\maketitle

\tableofcontents
\listofimps\index{implementation notes}

\chapter{Introduction}

\chapter{An Overview of the OCR API}

\chapter{The OCR API}

\section{Naming Conventions and Typeface Usage}

The OCR API defines four types of entities: functions, types, return codes, 
and constants. Functions always start with \func{ocr\_} and use exclusively 
lower case letters and underscores. When used in the body of this document, 
function names appear in bold monotype font, e.g., \func{ocr\_spawn()}. The 
functions associated with a particular conceptual category will share the same 
prefix. The conceptual categories are shown in Table~\ref{tab:prefixes}.

\begin{table}[h]
\centering
\begin{tabular}{|l|l|p{7cm}|}
\hline
\tbh{Prefix} & \tbh{Functional Group} & \tbh{Description} \\
\hline \hline
\texttt{ocr\_task\_} & \textit{Task management} & Routines that communicate 
with the runtime's scheduler, e.g. creating and modifying tasks and their 
behavior.\\
\texttt{ocr\_sync\_} & \textit{Synchronization} & Routines that deal with 
synchronization primitives. \\
\texttt{ocr\_atomic\_} & \textit{Atomic operations} & Routines that perform 
atomic memory operations, such as increment or compare-and-swap, with the 
appropriate implied memory barriers.\\
\hline
\end{tabular}
\caption{Runtime Function Prefixes\label{tab:prefixes}}
\end{table}

Type names also use lower case with underscores to separate words. Each type 
name starts with \dtype{ocr\_} and ends with \dtype{\_t}. When used in this 
document, type names appear in green monospaced font, e.g., 
\dtype{ocr\_typename\_t}.

Names for constants use upper case with underscores to separate words. Each 
constant name starts with \const{OCR\_}. When
used in the body of this report, constant names appear like this: 
\const{OCR\_CONSTANT}. Return codes are considered special constants, and as 
such are also bold, e.g., \retcode{OCR\_RETCODE}. 

The definition of named constants, function prototypes, and type definitions 
must be supplied in a file named \fname{ocr.h} that can be included by C and 
C++ programs using the runtime.

\section{Return Codes}

\newcommand{\ocrok}   {\retcodeIdx{OCR\_OK}\xspace}
\newcommand{\ocrfail} {\retcodeIdx{OCR\_FAIL}\xspace}
\newcommand{\ocrinval}{\retcodeIdx{OCR\_INVAL}\xspace}
\newcommand{\ocrperm} {\retcodeIdx{OCR\_PERM}\xspace}
\newcommand{\ocrmem}  {\retcodeIdx{OCR\_MEM}\xspace}
\newcommand{\ocrres}  {\retcodeIdx{OCR\_RES}\xspace}

The API specifies return codes that indicate success or failure of a function 
call. The only return codes that are required to be returned by an 
implementation are \ocrok and \ocrfail, however more detailed information may 
be provided in the case of failure via the additional return codes. For 
example, an implementation is free to allow the caller to trigger a 
segmentation fault when given an invalid address, rather than return 
\ocrinval. Table~\ref{tab:retcodes} lists all return codes used by the OCR.

\begin{table}[ht]
\centering
\begin{tabular}{|l|p{8cm}|}
\hline
\tbh{Symbol} & \tbh{Meaning} \\
\hline \hline
\ocrok & A return value that indicates operation success. \\
\ocrfail & A return value that indicates that the operation failed. \\
\ocrinval & A return value that indicates an invalid argument has been passed 
to an XThread function. Functions are not required to check the validity of 
arguments, but may do so. \\
\ocrperm & A return value that indicates that the operation was not permitted. 
\\
\ocrmem & A return value that indicates that the operation failed due to lack 
of memory. \\
\ocrres & A return value that indicates that the operation failed because the 
necessary resources were not available. \\
\hline
\end{tabular}
\caption{Return Codes\label{tab:retcodes}}
\end{table}

\section{Initialization and Cleanup}

\newcommand{\ocrinit}{ocr\_init}
\newcommand{\ocrfini}{ocr\_fini}
\newcommand{\ocrInit}{\funcIdx{\ocrinit()}\xspace}
\newcommand{\ocrFini}{\funcIdx{\ocrfini()}\xspace}

The OCR API includes a function, \ocrInit, to initialize the runtime, and a 
function, \ocrFini, to shut down the runtime.

\begin{FuncDesc}{\ocrinit}
The \ocrInit function initializes the runtime. \ocrInit must be called by a 
process before any other runtime functions may be used by any thread in the 
process. The \ocrInit function may be called by any thread in a multithreaded 
process. When it is called, the calling thread becomes schedulable within the 
runtime. \ocrInit calls are reference-counted, such that it may be called 
multiple times and only the first will actually initialize the runtime. An 
equal number of calls to \ocrFini must be made before the runtime is shut 
down.

\impnote{Nested Parallel Libraries}{The reference-counting of \ocrInit and 
\ocrFini calls allows for nested libraries that use the parallel runtime to 
operate without knowledge of each other. Other functions must not assume that 
only one library or program is using the runtime at any given time.}

\impnote{Environment Variables}{It is possible that various aspects of the 
runtime may be controlled by environment variables. This includes, but is not 
limited to, the actual level of parallelism in use, the use of locality and 
CPU-pinning, etc. Such values should be consistent across \ocrInit calls; 
returning an error code if they change between calls to \ocrInit is 
permissible, and even encouraged rather than changing the behavior of the 
runtime.}

\prototype{int}{\ocrinit}{\voidarg}

\begin{ReturnCodes}
    \rc{\ocrok}{Indicates success.}
    \rc{\ocrfail}{Indicates an error during initialization.}
\end{ReturnCodes}

\end{FuncDesc}

\begin{FuncDesc}{\ocrfini}

The \ocrFini function shuts down the runtime. This function \emph{must} be 
called by the same thread/task that called \ocrInit. The runtime may be later 
re-initialized by another call to \ocrInit.

\prototype{int}{\ocrfini}{\voidarg}

\begin{ReturnCodes}
    \rc{\ocrok}{Indicates success.}
    \rc{\ocrfail}{Indicates an error during shutdown that prevents the runtime 
from being re-initialized.}
\end{ReturnCodes}

\end{FuncDesc}

\section{Task Management}

\newcommand{\ocrTaskType}{\dtypeIdx{ocr\_task\_t}\xspace}
\newcommand{\ocrLocationType}{\dtypeIdx{ocr\_location\_t}\xspace}
\newcommand{\ocrAnyLocation}{\constIdx{OCR\_ANY\_LOCATION}\xspace}
\newcommand{\ocrDefaultStack}{\constIdx{OCR\_DEFAULT\_STACK}\xspace}
\newcommand{\ocrspawn}{ocr\_task\_spawn}
\newcommand{\ocryield}{ocr\_task\_yield}
\newcommand{\ocrSpawn}{\funcIdx{\ocrspawn()}\xspace}
\newcommand{\ocrYield}{\funcIdx{\ocryield()}\xspace}

The API includes a function, \ocrSpawn, to enqueue a new task to be executed 
by the runtime. It also includes function, \ocrYield, which allows any running 
task to yield execution control to another task (chosen by the runtime).

Tasks are functions that must be of the \ocrTaskType type, which requires that 
they match the following prototype:

\bareprototype{void}{function}{%
\lastargument{void *}{arg}}

Notably, this function prototype does not provide for a return value. Output 
values from such functions must be handled via pointers or pass-by-reference 
variables (in C++). Only a single pointer argument is provided; multiple 
argument marshaling can be done via any method (macros, arrays, structures, 
objects, etc.) that can use this. Synchronization to wait for a task to finish 
or to delay a task's start can be done via wrapper threads and/or data that is 
passed to the thread.

\begin{FuncDesc}{\ocrspawn}
The \ocrSpawn function creates a new task that will be executed by the 
runtime, within the current process. \ocrSpawn may be called from any thread, 
not necessarily one scheduled by the runtime. However, calling from within the 
runtime may be faster.

\prototype{int}{\ocrspawn}{%
\argument{const \ocrTaskType *}{func}
\argument{void *}{arg}
\argument{size\_t}{copydata}
\argument{size\_t}{stacksize}
\lastargument{\ocrLocationType}{where}}

\begin{ArgDesc}
    \argdesc{func}{input}{The function that will be executed as the task.}
    \argdesc{arg}{input}{An argument that will be passed to the task when it 
executes.}
    \argdesc{copydata}{input}{The number of bytes that will be copied from the 
\textit{arg} pointer and stored with the task. In this case, the value of 
\textit{arg} that is passed to the task will point to the copy of the data 
pointed to by \textit{arg} rather than be identical to the value of 
\textit{arg} that was passed in here. If this value is zero, the value of 
\textit{arg} will be passed to the task unmodified.}
    \argdesc{stacksize}{input}{The minimum amount of space reserved for the 
task's stack. A value of \ocrDefaultStack allows the library to decide.}
    \argdesc{where}{input}{The identifier of a location on which the thread 
must run. May be the constant \ocrAnyLocation, allowing the task to be 
executed anywhere.}
\end{ArgDesc}

\begin{ReturnCodes}
    \rc{\ocrok}{Indicates success.}
    \rc{\ocrfail}{Indicates a generic error in creating the task and 
    enqueueing it.}
    \rc{\ocrinval}{Indicates that one of the arguments is invalid.}
    \rc{\ocrmem}{Indicates that not enough memory could be allocated to 
enqueue the task. Memory requirements are likely to be (but not required to 
be) some function of stack size, context size, and \textit{copydata}.}
    \rc{\ocrres}{Indicates that a non-memory resource could not be allocated 
to enqueue the task.}
\end{ReturnCodes}

\impnote{Invalid Arguments}{Exactly which arguments to functions are checked 
for validity, and how they are checked, is left up to the implementation. For 
performance, these checks may be left out entirely.}

\end{FuncDesc}

\begin{FuncDesc}{\ocryield}

The \ocrYield function stops execution of the current task and allows another 
task to be scheduled.

\prototype{void}{\ocryield}{\voidarg}

\end{FuncDesc}

\section{Locations}

\subsection{Addressing}

\subsection{Memory Management}

\section{Synchronization and Communication}

\subsection{Atomic Operations}

\subsection{Blocking Operations}

\subsection{System Calls}

\subsection{Messaging}

\section{Checkpointing}

\chapter{The Semantics of Thread Execution}

\section{Locations}

\section{Scheduling}

%\nocite{*}
%\renewcommand{\bibname}{\chapter{References and More Information}}
%\bibliographystyle{plain}
%\bibliography{xthreads}

\printindex
\end{document}
